// 对于工程，用cargo doc 构建文档到 target/doc
// 对于工程，用cargo test --doc 仅运行文档测试
// 对于单个文件，用 rustdoc xx.rs 来生成文档
// 文档注释对于需要文档的大型项目来说非常重要。它们使用/// 标记，支持markdown

// 如果需要控制生成的文档图表，参考 https://rustwiki.org/zh-CN/rustdoc/the-doc-attribute.html
// 比如 html_logo_url 用来控制文档左上角的图标

#![crate_name = "doc"]
#![doc(html_logo_url = "https://example.com/logo.jpg")]

/// 这里给出一个“人”的表示
pub struct Person {
    /// 一个人必须有名字
    name: String,
}

impl Person {
    /// 返回具有指定名字的一个人
    ///
    /// # 参数
    /// * `name` - 字符串切片，代表人的名字
    ///
    /// # 示例
    /// ```
    /// // 在文档注释中，你可以书写代码块
    /// // 如果向`rustdoc` 传递 --test 参数，它还会帮你测试注释文档中的代码
    /// use doc::Person;
    /// let person = Person::new("name");
    /// ```
    pub fn new(name: &str) -> Person {
        Person {
            name: name.to_string(),
        }
    }

    /// 给一个友好的问候
    /// 对被叫到的 `Person` 说 “Hello, [name]”
    pub fn hello(&self) {
        println!("Hello, {}", self.name);
    }
}

fn main() {
    let p = Person::new("John");
    p.hello();
}